.. :validated: 3.0.0

Журналы событий и частые ошибки модуля синхронизации
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Возможности диагностики и категории ошибок
'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''

Данный раздел посвящён диагностике и устранению ошибок, возникающих при синхронизации между ALD Pro и Microsoft Active Directory (MS AD). Приведены типовые сценарии возникновения проблем, способы их диагностики, а также рекомендации по их устранению.

.. important::

   События, возникающие в процессе синхронизации, фиксируются в соответствующих журналах событий. Выполнение диагностики целесообразно начинать с анализа этих журналов.

Общие категории ошибок:

- Ошибки при установке и первоначальной настройке;
- Ошибки, возникающие при отсутствии связности между ALD Pro и MS AD;
- Ошибки при сопоставлении структур (например, дочерних подразделений) между ALD Pro и MS AD.

Ошибки могут проявляться при взаимодействии компонентов, выполняющих синхронизацию данных:

- компонент ``passwdhk``;
- служба ``syncer-watcher``;
- служба ``syncer-loadrunner``;
- cлужба ``pwdSync``.

Под данными службами подразумевается следующее:
- Служба syncer-watcher выполняет синхронизацию данных из LDAP контроллера MS AD в базу PostgreSQL на контроллера ALD Pro;
- Служба syncer-loadrunner выполняет синхронизацию из базы PostgreSQL в LDAP на контроллере ALD Pro;
- Служба pwdSync выполняет синхронизацию паролей пользователей в MS AD и ALD Pro.

Диагностика интеграции с MS AD
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Диагностическая информация модуля интеграции с MS AD фиксируется в журналах событий LSA (Login Security Authority). В этих журналах отражаются:

- Успешная смена пароля

.. figure:: images/45.png
   :name: 45

.. figure:: images/46.png
   :name: 46

- Неуспешная смена пароля

.. figure:: images/47.png
   :name: 47

.. figure:: images/48.png
   :name: 48

.. attention::
   
   **Типичная ошибка**:
   После вставки публичного ключа LDAP может возникнуть ошибка вида ``id2 not found``.
   **Решение**:
   Проверить директорию, в которую скопирован ключ. Убедиться, что путь указан верно, и повторно задать ключ в web-интерфейсе ALD Pro, если он не найден.

.. note::

   - При сопоставлении подразделений необходимо убедиться, что логин указывается в виде ``user@domain``, иначе возможны ошибки авторизации;
   - В случае потери ключа авторизации (например, ``id2 not found``), необходимо проверить директорию хранения ключей и выполнить переустановку через интерфейс управления.


Работа модуля синхронизации в режиме отладки
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. rubric:: Включение режима отладки модуля синхронизации

Для отладки работы модуля синхронизации необходимо включить режим отладки (**debug**):

.. code-block:: bash

   root@syncer-dc1:~# nano /opt/rbta/aldpro/syncer/.env
   DEBUG=True

**Файлы журналов событий:**

- `syncer_loadrunner.log` — отвечает за синхронизацию из PostgreSQL в ALD Pro:
  
  .. code-block:: bash

     /var/log/aldpro/syncer/syncer_loadrunner.log

- `syncer_watcher.log` — отвечает за чтение данных из MS AD и запись в PostgreSQL:

  .. code-block:: bash

     /var/log/aldpro/syncer/syncer_watcher.log

.. rubric:: Включение режима отладки для модуля **pwdSync**

Модуль синхронизации паролей между **MS AD** и **ALD Pro**  (``pwdSync``) поддерживает включение режима отладки через файл:

.. code-block:: bash

   root@syncer-dc1:~# nano /opt/rbta/aldpro/syncer/pwd_sync/standalone/__init__.py
   DEBUG = True

**Журналы:**

- Журнал отладки:

  .. code-block:: bash

     /var/log/aldpro/syncer/pwd_sync/standalone_debug.log

- Журнал ошибок:

  .. code-block:: bash

     /var/log/aldpro/syncer/pwd_sync/standalone_error.log

.. important::

   Текущая реализация не требует ручного перезапуска служб — запуск синхронизации осуществляется по расписанию **systemd** (таймеры, относящиеся к службам syncer-watcher, syncer-loadrunner, pwdSync).

Сценарии отладки
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Ниже представлены типовые сценарии поиска и устранения ошибок.

Проверка состояния служб
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Следует проверить, что таймеры служб активны, а службы запущены:

.. code-block:: bash

   systemctl status syncer-watcher.timer
   systemctl status syncer-loadrunner.timer
   systemctl status syncer-pwdsync.timer

   systemctl status syncer-watcher.service
   systemctl status syncer-loadrunner.service
   systemctl status syncer-pwdsync.service

При наличии ошибок рекомендуется проверить журнал службы:

.. code-block:: bash

   journalctl -u syncer-watcher.service
   journalctl -u syncer-loadrunner.service
   journalctl -u syncer-pwdsync.service


Ошибка дублирования имени при создании объекта
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Если имя пользователя или группы совпадает в ALD Pro и MS AD, процесс `syncer-loadrunner` завершится с ошибкой:

.. code-block:: text

   CRITICAL     ipa_load_runner   Объект objectGUID=2f880038-bba4-4f05-b115-8b3a8da217b5 не может быть создан в ALD Pro из-за дублирования имени.
   ERROR        ipa_load_runner   Объект не может быть создан в ALD Pro из-за дублирования имени.

**Решение**:
 - Переименовать объект в одном из источников;
 - Удалить объект из ALD Pro.

.. important::
   Перед началом синхронизации важно убедиться, что в настроенной точке синхронизации (подразделении) в MS AD и ALD Pro отсутствуют записи пользователей, групп, полностью идентичных друг другу (с одинаковыми именами). Если такие записи существуют, то в процессе синхронизации это приведет к ошибке и невозможности синхронизации.


Повторное появление удалённого объекта
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Если пользователь/группа была удалена из ALD Pro и корзины, но осталась в MS AD, она может быть вновь синхронизирована.

Примеры логов:

.. code-block:: text

   ERROR     ipa_load_runner   Объект objectGUID=... не найден в ALD Pro
   INFO      ipa_load_runner   Сохранение объекта objectGUID=..., sync_status=3
   CRITICAL  ipa_load_runner   Ошибка при обработке объекта. Требуется устранить ошибку вручную

**Решение**:

  - Удалить объект в MS AD или исключить его из области синхронизации;
  - Дождаться появления в корзине ALD Pro и удалить повторно.

Отладка проблемы: объект не создаётся в ALD Pro
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

**Пошаговая диагностика**:

1. Определить значение атрибута ``objectGUID`` объекта в LDAP MS AD;
2. Найти строки с ключевыми словами ``Error`` и нужным ``objectGUID`` в ``syncer_watcher.log``.

.. code-block:: bash

   grep '2f880038-bba4-4f05-b115-8b3a8da217b5' /var/log/aldpro/syncer/syncer_watcher.log

3. Найти строки с ключевыми словами `Error` и нужным `objectGUID` в `syncer_loadrunner.log`.

.. code-block:: bash

   grep '2f880038-bba4-4f05-b115-8b3a8da217b5' /var/log/aldpro/syncer/syncer_loadrunner.log

.. note::

   Если при создании точки синхронизации MS AD → ALD Pro задано одно сопоставление, второе сопоставление в той же точке будет невозможно. Такое поведение также фиксируется в логах и требует пересмотра структуры.

Неизвестный класс объекта в логах syncer-watcher
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

В процессе поиска объектов для синхронизации в журнале ``syncer-watcher.log`` могут встречаться ошибки следующего вида:

.. code-block:: text

   2025-06-25 07:12:03 syncer INFO     runners   Число объектов для обработки в watcher: 3
   2025-06-25 07:12:03 syncer INFO     runners   Обработка объектов
   2025-06-25 07:12:03 syncer ERROR    runners   Неизвестный класс объекта
   2025-06-25 07:12:03 syncer ERROR    runners   Неизвестный класс объекта
   2025-06-25 07:12:03 syncer ERROR    runners   Неизвестный класс объекта

.. note::

   Данная ошибка **не является критичной** и не влияет на дальнейшую работу службы **`syncer-watcher`**.

В процессе выполнения запроса к каталогу LDAP MS AD в результат поиска могут попасть **служебные объекты**, которые не подлежат синхронизации. Например:

.. code-block:: text

   # search reference
   ref: ldap://ForestDnsZones.corp.test/DC=ForestDnsZones,DC=corp,DC=test

   # search reference
   ref: ldap://DomainDnsZones.corp.test/DC=DomainDnsZones,DC=corp,DC=test

   # search reference
   ref: ldap://corp.test/CN=Configuration,DC=corp,DC=test

Подобные объекты игнорируются при синхронизации и не влияют на корректность основного процесса.

Ошибка удаления объекта, отсутствующего в ALD Pro
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Если объект был удалён из точки синхронизации (подразделения в MS AD) или перемещён в другое подразделение, **но при этом его уже нет в ALD Pro**, возможно появление ошибки при попытке удаления:

.. code-block:: text

   2025-06-25 11:26:41 syncer DEBUG     ipa_load_runner   Обработка объекта objectGUID=6cc876e1-40ae-44b3-b4a8-a9044f7dd69a, nsuniqueID=None, тип объекта=user, sync_status=3
   2025-06-25 11:26:41 syncer DEBUG     ipa_load_runner   Удаление объекта nsuniqueID=None
   2025-06-25 11:26:41 syncer DEBUG     provider   Запрос для объекта в целевой LDAP используя метод user_del
   2025-06-25 11:26:41 syncer ERROR     ipa_load_runner   Ошибка во время удаления {'code': 4001, 'message': 'user1: user not found', 'data': {'reason': 'user1: user not found'}, 'name': 'NotFound'}
   2025-06-25 11:26:41 syncer INFO      ipa_load_runner   Сохранение объекта objectGUID=6cc876e1-40ae-44b3-b4a8-a9044f7dd69a, nsuniqueID=None с sync_status=0
   2025-06-25 11:26:41 syncer INFO      ipa_load_runner   Удаление записи 1 в точки синхронизации

Ошибка **`user not found`** означает, что в ALD Pro уже нет объекта, который предполагается удалить. Это может произойти, если:

- объект был удалён вручную или автоматически на предыдущих этапах;
- объект изначально не был синхронизирован, но был добавлен в список на удаление из-за изменений в MS AD.

**Решение**: данная ошибка не требует вмешательства. При следующем запуске службы **`syncer-loadrunner.service`** состояние синхронизации будет скорректировано, и сообщение об ошибке исчезнет.

Ошибка отсутствия TLS-сертификата для подключения к MS AD
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Если в процессе подключения к целевому контроллеру MS AD отсутствует необходимый файл TLS-сертификата, в журнале `syncer_loadrunner.log` появится следующая ошибка:

.. code-block:: text

   2025-06-27 03:19:06 syncer DEBUG     strategy   Подключение к хосту dc1.ald.company.lan успешно. Протокол API
   2025-06-27 03:19:06 syncer DEBUG     provider   Подключение к целевой LDAP
   2025-06-27 03:19:06 syncer DEBUG     strategy   Попытка подключения к dc1.ald.company.lan
   2025-06-27 03:19:06 syncer ERROR     ipa_load_runner   Нет файла сертификата для подключения id=1
   Traceback (most recent call last):
     ...
   AttributeError: Нет файла сертификата для подключения id=1
   2025-06-27 03:19:06 syncer DEBUG     provider   Отключение соединения от целевой LDAP
   2025-06-27 03:19:06 syncer INFO      ipa_load_runner   loadrunner завершился

**Причина**: отсутствует файл публичного ключа для LDAPS-подключения к контроллеру MS AD.

**Решение**:
Скопировать сертификат `sert.pem` в требуемое расположение:

.. code-block:: bash

   cp sert.pem /run/syncer/provider/key1.pem

Где `sert.pem` — это публичный ключ для LDAPS-подключения.

Либо проверить директорию, в которую скопирован ключ. Убедиться, что путь указан верно, и повторно задать ключ в web-интерфейсе ALD Pro, если он не найден.

Подробнее о подготовке и настройке сертификатов (см. **Справочные материалы** → **Инструкция по дополнительной настройке модуля синхронизации** → :ref:`cert_ms_ad`).

Отсутствие связи с контроллером MS AD
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Если со стороны ALD Pro отсутствует сетевое соединение с контроллером MS AD, в журнале `syncer_watcher.log` зафиксируется ошибка следующего вида:

.. code-block:: text

   2025-06-30 14:43:52 syncer DEBUG     provider   Подключение к LDAP источник
   2025-06-30 14:43:52 syncer DEBUG     strategy   Попытка подключения к windc1.corp.test
   2025-06-30 14:43:55 syncer ERROR     strategy   {'desc': "Can't contact LDAP server", 'errno': 107, 'info': 'Transport endpoint is not connected'}
   2025-06-30 14:43:58 syncer ERROR     strategy   {'desc': "Can't contact LDAP server", 'errno': 107, 'info': 'Transport endpoint is not connected'}
   syncer ERROR     run   Не удалось подключиться к хосту=windc1.corp.test. Протокол LDAP

**Решение**:  
Проверить доступность порта **389** на контроллере MS AD

.. code-block:: bash

   nc -vz windc1.corp.test 389

Если порт недоступен — устранить ограничения, связанные с настройками сетевых экранов, маршрутизацией и другими компонентами инфраструктуры.

Неверный пароль при доступе из web-интерфейса АLD Pro
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

В случае, когда  web-интерфейсе ALD Pro неверно указано пароль пользователя, под которым происходит подключение к LDAP MS AD, в файле ``syncer_watcher.log`` будет ошибка:

.. code-block:: text

   2025-07-02 12:17:40 syncer DEBUG     provider   Подключение к LDAP источник
   2025-07-02 12:17:40 syncer DEBUG     strategy   Попытка подключения к windc1.corp.test
   2025-07-02 12:17:40 syncer ERROR     strategy   {'desc': 'Invalid credentials', 'info': '80090308: LdapErr: DSID-0C09042A, comment: AcceptSecurityContext error, data 52e, v3839'}
   2025-07-02 12:17:40 syncer ERROR     strategy   {'desc': 'Invalid credentials', 'info': '80090308: LdapErr: DSID-0C09042A, comment: AcceptSecurityContext error, data 52e, v3839'}
   syncer ERROR     run   Не удалось подключиться к хосту=windc1.corp.test. Протокол LDAP

**Решение**:  
Проверить правильность ввода пароля.

Проблемы с синхронизацией пароля новых пользователей MS AD
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

При первой попытке синхронизации пароля пользователя из Microsoft Active Directory в ALD Pro может возникать при условиях:

- данный пользователь только что создан в MS AD;
- пароль пользователя ни разу не изменялся в MSAD;
- синхронизация завершилась с ошибкой.

При попытке синхронизации данных пользователя из MS AD в ALD Pro журнал работы модуля синхронизации ``syncer`` (файл ``syncer_standalone_error.log``) содержит записи следующего вида:

.. code-block:: text

   2025-08-24 13:06:49 pwd-sync ERROR  utils  Возникло исключение во время выполнения <function ADldap.delete_attr ...>
   2025-08-24 13:06:55 pwd-sync ERROR  processors  Ошибка NO_SUCH_ATTRIBUTE, текст ошибки {'desc': 'No such attribute', 'info': '00002076: AtrErr: DSID-030F194C, ... (userParameters)'}
   Traceback (most recent call last):
     ...
   ldap.NO_SUCH_ATTRIBUTE: {'desc': 'No such attribute', 'info': '00002076: AtrErr: DSID-030F194C, ... Att 9008a (userParameters)'}

**Причина**:

У новых пользователей MS AD, для которых пароль ещё ни разу не был изменён, отсутствует ряд служебных атрибутов (например, ``userParameters`` и ``whenChanged``).  
При первой синхронизации из ALD PRO модуль ``syncer`` пытается работать с этими атрибутами, и каталог возвращает ошибку ``NO_SUCH_ATTRIBUTE``.  
В результате синхронизация пароля не выполняется.

**Решение**:

Для всех новых пользователей, созданных в MS AD, необходимо **однократно сменить пароль** (достаточно через стандартные средства Windows или административные утилиты).  
После этого в каталоге будут установлены значения атрибутов (в том числе ``whenChanged``), и последующая синхронизация паролей из ALD PRO в MS AD будет выполняться без ошибок.
